home *** CD-ROM | disk | FTP | other *** search
/ Apple WWDC 1996 / WWDC96_1996 (CD).toast / Technology Materials / MacOS 8 Resources / Developer Tools / Mac OS 8 Interfaces & Libraries / Interfaces / PInterfaces / CoachMarks.p < prev    next >
Encoding:
Text File  |  1996-05-01  |  7.6 KB  |  224 lines  |  [TEXT/MPS ]
  1. {
  2.      File:        CoachMarks.p
  3.  
  4.      Contains:    Public CoachMark programming interface.
  5.  
  6.      Version:    Technology:    Copland
  7.                  Release:    Universal Interfaces 3.0d3 on Copland DR1
  8.  
  9.      Copyright:    © 1984-1996 by Apple Computer, Inc.  All rights reserved.
  10.  
  11.      Bugs?:        If you find a problem with this file, send the file and version
  12.                  information (from above) and the problem description to:
  13.  
  14.                      Internet:    apple.bugs@applelink.apple.com
  15.                      AppleLink:    APPLE.BUGS
  16.  
  17. }
  18. {$IFC UNDEFINED UsingIncludes}
  19. {$SETC UsingIncludes := 0}
  20. {$ENDC}
  21.  
  22. {$IFC NOT UsingIncludes}
  23.  UNIT CoachMarks;
  24.  INTERFACE
  25. {$ENDC}
  26.  
  27. {$IFC UNDEFINED __COACHMARKS__}
  28. {$SETC __COACHMARKS__ := 1}
  29.  
  30. {$I+}
  31. {$SETC CoachMarksIncludes := UsingIncludes}
  32. {$SETC UsingIncludes := 1}
  33.  
  34. {$IFC UNDEFINED __TYPES__}
  35. {$I Types.p}
  36. {$ENDC}
  37. {$IFC UNDEFINED __SOUND__}
  38. {$I Sound.p}
  39. {$ENDC}
  40. {$IFC UNDEFINED __WINDOWS__}
  41. {$I Windows.p}
  42. {$ENDC}
  43. {$IFC UNDEFINED __HIWINDOWTYPES__}
  44. {$I HIWindowTypes.p}
  45. {$ENDC}
  46.  
  47. {$PUSH}
  48. {$ALIGN MAC68K}
  49. {$LibExport+}
  50.  
  51. {$IFC FOR_SYSTEM8_COOPERATIVE }
  52. {
  53.  Attributes —————————————————————————————————————————————————————————————————————————————————————————————
  54.  animation speeds
  55. }
  56.  
  57. CONST
  58.     kCoachMarkFastest            = 0;
  59.     kCoachMarkSlowest            = 31;
  60.  
  61. {  sloppiness }
  62.     kPerfectCoachMark            = 0;
  63.     kSloppyCoachMark            = 100;
  64.  
  65. {  translucency }
  66.     kMaxCoachMarkWeight            = 100;
  67.     kDefaultCoachMarkRegularWeight = 75;
  68.     kDefaultCoachMarkHiddenWeight = 25;
  69.  
  70. {  stroke width }
  71.     kDefaultCircleCoachMarkThickness = 12;
  72.     kDefaultUnderlineCoachMarkThickness = 8;
  73.     kDefaultXCoachMarkThickness    = 15;
  74.     kDefaultArrowCoachMarkThickness = 7;
  75.     kDefaultHighlighterCoachMarkThickness = 5;
  76.  
  77. {  Selectors ——————————————————————————————————————————————————————————————————————————————————————————————— }
  78.     kCircleCoachMark            = 1;
  79.     kUnderlineCoachMark            = 2;
  80.     kXCoachMark                    = 3;
  81.     kArrowCoachMark                = 4;
  82.     kHighlighterCoachMark        = 5;
  83.     kNumCoachMarkTypes            = 5;
  84.  
  85.  
  86. TYPE
  87.     CoachMarkType                        = UInt32;
  88.  
  89. CONST
  90.     kCoachMarkStraight            = 0;
  91.     kCoachMarkCurvesUp            = 1;
  92.     kCoachMarkCurvesDown        = 2;
  93.  
  94.  
  95. TYPE
  96.     CoachMarkCurvature                    = UInt32;
  97. {
  98.  Flags ———————————————————————————————————————————————————————————————————————————————————————————————————
  99.  theme element inheritance flags -- is "heritage" and "inherit" too wordy?  Could use a scheme based on the word "trait"
  100. }
  101.  
  102. CONST
  103.     kCoachOverrideThemeNothing    = 0;
  104.     kCoachOverrideThemeColor    = $01;
  105.     kCoachOverrideThemeOpacity    = $02;
  106.     kCoachOverrideThemeSloppiness = $04;
  107.     kCoachOverrideThemeStrokeWidth = $08;
  108.     kCoachOverrideAllThemeTraits = $FFFFFFFF;
  109.  
  110.  
  111. TYPE
  112.     CoachThemeOverrideFlags                = UInt32;
  113.  
  114. CONST
  115.     kCoachMarkDefaultAnimation    = 0;
  116.  
  117.  
  118. TYPE
  119.     CoachAnimationType                    = UInt32;
  120. {
  121.  In which direction should the animation go? For an arrow or underline
  122.  this is inherent in the geometry. For the others, some bit flags:
  123. }
  124.  
  125. CONST
  126.     kCoachMarkDefaultDirection    = 0;                            {  for circle:  }
  127.     kCoachMarkClockwise            = $0000;
  128.     kCoachMarkCounterClockwise    = $0001;                        {  X stroke direction:  }
  129.     kCoachMarkTopLeftToBottomRightMask = $0000;
  130.     kCoachMarkBottomRightToTopLeftMask = $0004;                    {  X stroke direction:  }
  131.     kCoachMarkTopRightToBottomLeftMask = $0000;
  132.     kCoachMarkBottomLeftToTopRightMask = $0008;                    {  which X stroke is first:  }
  133.     kCoachMarkTopLeftToBottomRightFirstMask = $0000;
  134.     kCoachMarkTopRightToBottomLeftFirstMask = $0010;
  135.  
  136.  
  137. TYPE
  138.     CoachDirection                        = UInt32;
  139. {  to specify how to erase a coach mark }
  140.  
  141. CONST
  142.     kCoachMarkDefaultErase        = 0;
  143.  
  144.  
  145. TYPE
  146.     CoachMarkEraseOptions                = UInt32;
  147. {
  148.  Structures —————————————————————————————————————————————————————————————————————————————————————————
  149.  opaque reference to a coach mark
  150. }
  151.     CoachMarkRef = ^LONGINT;
  152. {  CoachMarkRec specifies the appearance of a CoachMark }
  153.     CoachMarkRecPtr = ^CoachMarkRec;
  154.     CoachMarkRec = RECORD
  155.         markType:                CoachMarkType;                            {  which shape of mark? }
  156.         themeOverrides:            CoachThemeOverrideFlags;                {  which values do we get from the theme?  }
  157.         color:                    RGBColor;                                {  what color shall the CoachMark be? }
  158.         sound:                    Handle;                                    {  sound to be played upon drawing the coachmark (••• Doesn’t work in D11) }
  159.         regularPercentage:        UInt16;                                    {  0..100    - opacity as drawn within the specified grafport }
  160.         hiddenPercentage:        UInt16;                                    {  0..100    - opacity as drawn outside the specified grafport }
  161.         sloppiness:                UInt16;                                    {  0..100 }
  162.         thickness:                UInt16;                                    {  in pixels }
  163.         curvature:                CoachMarkCurvature;                        {  direction of bulge for line-like marks }
  164.     END;
  165.  
  166. {  CoachMarkAnimation specifies the appearance of a coach mark's animation }
  167.     CoachMarkAnimationPtr = ^CoachMarkAnimation;
  168.     CoachMarkAnimation = RECORD
  169.         effectType:                CoachAnimationType;
  170.         speed:                    UInt32;
  171.         direction:                CoachDirection;
  172.     END;
  173.  
  174. {
  175.  The Freaky Good Stuff ———————————————————————————————————————————————————————————————————————————————
  176.  Creation/destruction
  177. }
  178. FUNCTION NewCoachMarkRef({CONST}VAR appearance: CoachMarkRec; VAR newCoachMark: CoachMarkRef): OSStatus; C;
  179. FUNCTION GetNewCoachMarkRef(resID: SInt16; VAR newMark: CoachMarkRef): OSStatus; C;
  180. FUNCTION DisposeCoachMark(theMark: CoachMarkRef): OSStatus; C;
  181. {  To specify geometry }
  182. FUNCTION CoachRectOnWindow(mark: CoachMarkRef; VAR window: HIWindow; {CONST}VAR localRect: Rect): OSStatus; C;
  183. FUNCTION CoachGlobalRect(mark: CoachMarkRef; {CONST}VAR globalRect: Rect): OSStatus; C;
  184. FUNCTION CoachStrokeOnWindow(theMark: CoachMarkRef; VAR window: HIWindow; {CONST}VAR localSource: Point; {CONST}VAR localDest: Point): OSStatus; C;
  185. FUNCTION CoachGlobalStroke(theMark: CoachMarkRef; {CONST}VAR globalSource: Point; {CONST}VAR globalDest: Point): OSStatus; C;
  186. {  Accessors }
  187. FUNCTION GetCoachMarkType(theMark: CoachMarkRef): CoachMarkType; C;
  188. FUNCTION GetCoachMarkWindow(theMark: CoachMarkRef): HIWindowPtr; C;
  189. FUNCTION GetCoachMarkRect(mark: CoachMarkRef; VAR globalRect: Rect): OSStatus; C;
  190. FUNCTION GetCoachMarkStroke(theMark: CoachMarkRef; VAR globalSource: Point; VAR globalDest: Point): OSStatus; C;
  191. FUNCTION SetCoachMarkColor(theMark: CoachMarkRef; {CONST}VAR color: RGBColor): OSStatus; C;
  192. FUNCTION GetCoachMarkColor(theMark: CoachMarkRef; VAR color: RGBColor): OSStatus; C;
  193. FUNCTION SetCoachMarkRegularWeight(theMark: CoachMarkRef; weight: UInt16): OSStatus; C;
  194. FUNCTION GetCoachMarkRegularWeight(theMark: CoachMarkRef): UInt16; C;
  195. FUNCTION SetCoachMarkHiddenWeight(theMark: CoachMarkRef; weight: UInt16): OSStatus; C;
  196. FUNCTION GetCoachMarkHiddenWeight(theMark: CoachMarkRef): UInt16; C;
  197. FUNCTION SetCoachMarkThickness(theMark: CoachMarkRef; thickness: UInt16): OSStatus; C;
  198. FUNCTION GetCoachMarkThickness(theMark: CoachMarkRef): UInt16; C;
  199. FUNCTION SetCoachMarkSloppiness(theMark: CoachMarkRef; sloppiness: UInt16): OSStatus; C;
  200. FUNCTION GetCoachMarkSloppiness(theMark: CoachMarkRef): UInt16; C;
  201. FUNCTION SetCoachMarkCurvature(theMark: CoachMarkRef; curvature: CoachMarkCurvature): OSStatus; C;
  202. FUNCTION GetCoachMarkCurvature(theMark: CoachMarkRef): CoachMarkCurvature; C;
  203. FUNCTION SetCoachMarkThemeOverrides(theMark: CoachMarkRef; inHeritage: CoachThemeOverrideFlags): OSStatus; C;
  204. FUNCTION GetCoachMarkThemeOverrides(theMark: CoachMarkRef; VAR outHeritage: CoachThemeOverrideFlags): OSStatus; C;
  205. {
  206.  Drawing, animation, erasing
  207.  CoachMarkInteraction is synchronous and applies globallly, the other three are not and require windows
  208. }
  209. FUNCTION CoachMarkInteraction(theMark: CoachMarkRef; {CONST}VAR effect: CoachMarkAnimation): OSStatus; C;
  210. FUNCTION AnimateCoachMark(theMark: CoachMarkRef; {CONST}VAR effect: CoachMarkAnimation): OSStatus; C;
  211. FUNCTION DrawCoachMark(theMark: CoachMarkRef): OSStatus; C;
  212. FUNCTION EraseCoachMark(theMark: CoachMarkRef; options: CoachMarkEraseOptions): OSStatus; C;
  213. {$ENDC}
  214. {$ALIGN RESET}
  215. {$POP}
  216.  
  217. {$SETC UsingIncludes := CoachMarksIncludes}
  218.  
  219. {$ENDC} {__COACHMARKS__}
  220.  
  221. {$IFC NOT UsingIncludes}
  222.  END.
  223. {$ENDC}
  224.